The jstools package provides a Find Panel, shared by several applications, which lets you search for a string of text, and optionally replace it with another string of text. The full functionality of the Find Panel is available if you're searching in a text window you can edit (as in the editor, jedit); a subset of the features is available if you're searching in a text window you can't edit (as in jdoc or jmore).
The Find Panel is implemented by the jfindpanel.tcl library; if you're a Tk programmer, you can use it in your own applications.
This document describes the Find Panel provided by version 3.6/3.0 of the jstools libraries.
Usage
The Find Panel has two fields for you to type the search string (or pattern) and the replacement string into, and four buttons: `Search', `Replace', `Replace All', and `Cancel'. There are also some checkbuttons which control the Find Panel's behaviour, which are described under Find Panel Options below. (Not all these features will be available if the window you're searching in isn't editable; see Searching in Non¡Editable Windows for details.)
If all you want to do is find the next occurrence of a string, you can just type the string you want to search for in the `Search for:' field, and click `Search' (or just press Return). The Find Panel will find the next occurrence of the string in the text after the insertion point (the blinking vertical bar) and select it. (If the string you typed didn't appear in the text after the insertion point, an alert panel will tell you so.)
If you want to search repeatedly through the text for a particular string, you can keep clicking on the `Search' button (or pressing Return).
To replace a string, type the search string in the `Search for:' field, and type the replacement string in the `Replace with:' field. Then click on Search to find and select the next ocurrence of the search string, and click on `Replace' to replace it and continue the search. Clicking `Replace' replaces whatever the current selection is (it doesn't necessarily have to be the result of a search) with the text in the `Replace with:' field.
You can click on `Replace All' to replace the search string (the contents of the `Search for:' field) with the replacement string (the contents of the `Replace with:' field) everywhere in the text. This should be done with some caution, of course.
(If you need to search for or substitute a newline or a tab, you can type them in the search and replace fields as Control-J and Control-I, respectively. No, it's not intuitive, but it works.)
The `Cancel' button makes the find panel go away and returns you to editing your text.
Searching in Non¡Editable Windows
If the text window you're searching in is not editable (as in the jmore application), then the Find Panel features that allow you to replace text are not available. The `Replace with:' field, the `Replace' button, and the `Replace All' button will not be displayed in this case.
Using the Find Panel with a non¡editable window is a little tricky, because the Find Panel searches from the insertion point in a text window. In an editable window, the insertion point is displayed as a blinking vertical bar, but in a non¡editable window it's invisible. So it may be hard to tell where the search is starting from. If you can't find a string you're fairly sure is in the text, you can try scrolling the text window up to the top and clicking in the upper¡left corner to set the insertion point at the beginning of the text.
Find Panel Options
If the `Backwards' checkbutton is selected, the search will be backwards in the text from the current insertion point; otherwise it will be forwards.
If the `Case¡sensitive' checkbutton is selected, then the Find Panel will only search for an exact match, so that if you search for `because', you won't find `Because'. Normally, case is ignored when searching, so `because' and `Because' (and `BECAUSE' and `becausE') will match.
In any case, if you search for `because of' with one space, you won't find `because of' with two spaces.
If the `Regex' checkbutton is selected, then searching and replacement will be done using regular expressions rather than fixed strings. Regular expressions allow you to express more complicated patterns than just specific sequences of characters; for instance, you could search for all words that are in all capitals, or all occurrences of a number in parentheses. You can also use fragments of the matched text in the replacement text. For the details of regular expressions, see the Tcl regexp(n) and regsub(n) manual pages. (Another place to look for information is the REGULAR EXPRESSIONS section of the ed(1) manual page, although the regular expressions in ed(1) differ slightly from those used by Tcl.)
Currently, you can only search forward for regular expressions; if you have both `Regex' and `Backwards' selected, you'll get a notice telling you so when you click `Search'.
Evolution
Feel free to report bugs (and feature requests) to me, <js@bu.edu>, and I will try to deal with them. Also, feel free to fix bugs or add features on your own and let me know how you did it.
Bugs and Limitations
* The Find Panel makes copies of the text in the text window to search in, so it may be wasteful of memory and slow with windows containing lots of text.
* You can't search backwards for a regular expression.
Future Directions
* There should be a way to highlight all occurrences of a string, rather than just jumping to each one in succession.
